home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Add-Ons / After Dark / The Swarm 1.5 / The Swarm README < prev   
Text File  |  1995-12-05  |  13KB  |  272 lines
  1. _______________________________________________________________
  2. THE SWARM 1.5  —  A freeware Screensaver Module
  3.  
  4. By Leo Breebaart, Copyright ©1994-95 Kronto Software
  5.  
  6. Internet e-mail: leo@cp.tn.tudelft.nl        
  7. Internet WWW page: http://www.cp.tn.tudelft.nl/leo/kronto.html
  8. _______________________________________________________________
  9.  
  10.  
  11. Description
  12.  
  13.   The Swarm is a simple, but surprisingly elegant and mesmerizing
  14.   line animation, in which a number of small line segments (the ‘bees’)
  15.   chase one other segment (the ‘queen bee’) across the screen.
  16.   
  17.  
  18. Features
  19.  
  20.     •    Compatible with After Dark (both 2.0 and 3.0), DarkSide of the Mac and UnderWare.
  21.     •  Flicker-free animation with smooth fade-out/fade-in effects.
  22.   •  Intelligent Demo Mode (as if anybody cares :—) ).
  23.     •  Does not use any permanent System memory under After Dark 2.0.
  24.     •  Has an animated About Box and thumbnail.
  25.     •  Runs under both MultiModule and the Randomizer — without crashing.
  26.     •  Comes with extensively documented source code (CodeWarrior 7 C format).
  27.     •  Both the module and the source code are free.
  28.   
  29.  
  30. Restrictions & Technical Remarks
  31.  
  32.   •    The Swarm needs Color QuickDraw to run. A color screen is not essential,
  33.     however: on a Black & White SE/30 the module works just fine.
  34.  
  35.   •  Multiple-monitor setups are supported, but not actively used — the animation
  36.     always runs on the main monitor only (and will simply black out any other screens).
  37.  
  38.     •  I cannot guarantee that The Swarm will work with versions of After Dark
  39.     earlier than 2.0u. The same holds for any other programs that are supposed
  40.     to be able to play After Dark modules (except for DarkSide and UnderWare,
  41.     which I had access to). In all such cases, The Swarm may run, or it may not.
  42.     Feedback about compatibility issues will be much appreciated.
  43.     
  44.     •  At the moment of writing the latest version numbers of the screensavers
  45.     The Swarm has been tested to work with are 3.0b for After Dark, 4.2 for DarkSide
  46.     and 1.0.1 for UnderWare. Free updaters for these programs are readily available
  47.     on the Internet and on all the major commercial software archives. See also the
  48.     URL appendix at the end of this document.
  49.         
  50.  
  51. Who thought of it first
  52.  
  53.   I first came across this animation in an X Windows program called xswarm,
  54.   written by Jeff Butterworth in the early 90s. I liked it so much that I
  55.   decided to write an After Dark version. Most of the module I had to create
  56.   from scratch, but the core algorithm was taken straight from Jeff’s
  57.   sources. My module, of course, lacks all the many options that his X Windows
  58.   program has. If you have access to an appropriate machine, be sure to
  59.   check out xswarm — it’s great.
  60.     
  61.   Shortly after I began programming this module it was brought to my
  62.   attention that there already was a ‘swarm’ After Dark module, called
  63.   ColorSwarm!, written by Dan Walkowski in 1991.
  64.  
  65.   Since his module looked a bit different from what I had in mind, I just went
  66.   ahead and wrote my own version anyway. But be sure to check out his module. 
  67.   He has more parameters for you to set, his ColorSwarm! works on B&W
  68.     machines without Color QuickDraw, and I believe he also makes use of multiple 
  69.     monitors, which I don’t.
  70.   
  71.   
  72. Version history
  73.  
  74.     1.0        25 Mar 1994
  75.                         —    Initial release.
  76.  
  77.     1.1        24 Feb 1995
  78.                         —    Bees on 256-color screens will now change color as they move along. Added
  79.                                 a new slider to control the color-changing speed. 
  80.                         —    Had to sacrifice the 'smooth fade' checkbox to make room for the new slider.
  81.                                 The Swarm now always fades smoothly, if possible.
  82.                         —    The About Box now wil take advantage of After Dark 3.0’s expanded
  83.                                 about box area (provided you’re running 3.0, of course. Duh.).
  84.                         —    Added animated thumbnail for After Dark 3.0.
  85.                         —    Cleaned up the source code.
  86.  
  87. 1.1.1    19 May 1995
  88.                         —    Fixed a bug that caused crashes for people running the module on a Mac IIsi
  89.                                 under DarkSide.
  90.                         —    Shortened the duration of the fade-out when the module kicks in, and entirely
  91.                                 removed the fade-in when the module ends. Having to wait so long for the 
  92.                                 fade effects to take place got on people’s nerves (including mine).
  93.                         —    Removed all references to the After Dark FTP Site and the Programmers’ List,
  94.                                 because both are now (temporarily) defunct.
  95.     
  96. 1.5            5 December 1995
  97.                         —    The Swarm is now a FAT module that will run native on PowerMacs, provided
  98.                                 you are using After Dark 3.0 or later.
  99.                         —    Code ported to CodeWarrior.
  100.                         —    Many internal improvements to the code and the project structure. The module
  101.                                 should now react much more gracefully to error conditions.
  102.  
  103.  
  104. Credits & Acknowledgments
  105.  
  106.   First of all, my thanks to Jeff Butterworth for giving me permission to ransack 
  107.     his code and port his algorithm to the Mac.
  108.  
  109.     Frits Kuijlman did the initial port of the code from THINK C to CodeWarrior, and helped me
  110.     figure out how to get the module to run native on a PowerMac.
  111.  
  112.     Neither Frits nor I would have had much success, however, if Robert Geisler had not shown
  113.     us the way. Without his Fat Module code this version of The Swarm would not have happened.
  114.  
  115.   For technical assistance, emotional support and beta-testing I owe a sincere 
  116.   thank-you to Rodney “Jewelbox” Jacks, to Lloyd “Screensaver FAQ” Wood, and to 
  117.   all the members of the After Dark programmers mailing list. 
  118.  
  119.     Without Timo Eloranta’s error reports and his willingness to crash his Mac for me I
  120.     would never have been able to track down the IIsi-killing bug in version 1.1.
  121.  
  122.   Special thanks to Jonas Englund, for allowing me to use, adapt and distribute
  123.   his CLUT fading code.
  124.   
  125.   Extra special thanks to David “Bat Signal” Zwiefelhofer, to Joseph 
  126.   “Peek-a-Boo” Judge, and to Berkeley Systems themselves for releasing sample 
  127.   source code and documentation without which this module would never have 
  128.   been written in the first place.
  129.   
  130.     The Swarm was created using CodeWarrior 7,  Think Reference 2.0.1,
  131.     ResEdit 2.1.3, BBEdit 3.5.1, and Adobe Photoshop 3.0.1.
  132.  
  133.  
  134. Known Problems
  135.  
  136.     •    The color-changing bees was the single most-requested feature for
  137.     The Swarm, so I added it. However, the current implementation is just
  138.     a quick interim hack to make it work for at least some of the people. In
  139.     particular: the bees will only change color on displays in 8-bit (256 color)
  140.     mode, never in modes with a higher or lower number of colors. Fixing this
  141.     will be one of the top priorities for the next version of The Swarm.
  142.  
  143.     •    The color-changing slider has no effect in demo-mode.
  144.  
  145.     •    Under certain very rare circumstances (specifically: if you have a
  146.     multi-monitor setup in which your main monitor (the one with the menu
  147.     bar) is not placed in the ‘left-upper-most’ position in the Monitors control
  148.     panel) the module will start drawing garbage on your screen when
  149.     activated. This is an entirely cosmetic bug, and I know precisely what’s
  150.     causing it — I just don’t know how to fix it, yet.
  151.  
  152.     •    Under certain other not-so-rare circumstances (specifically: if After
  153.     Dark starts displaying a “Please Wake Up” message while the module
  154.     is running, e.g. when a background application wants your attention) the
  155.     module will also start drawing garbage to your screen. This too, is an entirely
  156.     cosmetic bug — but I’l be darned if I know what’s causing it, or how to
  157.     fix it.
  158.  
  159.     •    The Swarm can cause crashes on the Macintosh IIsi, which may or may
  160.     not be related to problems with a special kind of video card.
  161.  
  162.     •    Those of you interested in the source code should be aware (you may
  163.     have already gathered it from the above few paragraphs :-) ) that I am
  164.     not an experienced Macintosh programmer — in fact, The Swarm was my
  165.     very first programming effort for the Mac. This means that the code
  166.     may have hidden problems that I’m simply not aware of. Don’t assume
  167.     that I’m always doing things the ‘right’ way.
  168.        
  169.     I would appreciate hearing about any other bugs or problems you may encounter 
  170.     with The Swarm.
  171.         
  172.         
  173. A Word about Memory and CPU-time
  174.  
  175.   The Swarm tries to be a well-behaved, system-friendly module. It will, for
  176.   instance, not reserve any permanent memory in your system heap. That
  177.   means that having The Swarm selected costs you no more memory than having
  178.   the default ‘Starry Night’ module selected, as long as After Dark has not
  179.   taken over the screen.
  180.   
  181.   Of course, once After Dark kicks in, The Swarm does need loads of memory
  182.   for its animation (the larger your screen the worse it gets), which it
  183.   will try to allocate out of the free memory you have at that moment. In
  184.   low-memory situations (e.g. if you have lots of applications open), this
  185.   attempt may be unsuccessful, and the module will refuse to run with an
  186.   appropriate error message. The reason I am explaining all of this in such
  187.   detail is that the upshot of this strategy is that you may see The Swarm
  188.   ‘fail’ to run more often than other modules. But that is entirely
  189.   intentional, and only means that it is your real applications which are
  190.   getting access to every last Kb of your available memory. Isn’t that how 
  191.   things should be?
  192.   
  193.   On fast Macs (Quadra’s or higher), finally, you will want to use the ‘Swarm
  194.   Speed’ slider in the control panel to slow the animation down. Here too, I 
  195.   just want to point out that if you do this, then the extra CPU time will be
  196.   given back to the system. The Swarm will never use more processing power
  197.   then it really needs.
  198.  
  199.         
  200. Still To Do
  201.  
  202.   Version 1.5 is still just a minor upgrade to version 1.0. There will be a major new 
  203.     version of The Swarm, although for the coming months (I’m writing this in 
  204.     December 1995) I won’t have time to work on it, sorry. For The Swarm 2.0
  205.     I intend the following features and fixes:
  206.   
  207.     •    Allow color-changing bees on non-CLUT devices (i.e. non-8-bit modes)
  208.   •    Add more parameters for you to play with.
  209.     •    Make Queen Bee behave more intelligently and interestingly.
  210.   •    Multiple Swarms, or maybe multiple Queen Bees (there’s a difference!).
  211.   •    Add sound/music.
  212.   •    Add an option to make the entire Swarm move 3-dimensionally, with
  213.             depth indicated by perspective projection and color brightness.
  214.   •  Support old, non-Color Quickdraw B&W Macs.
  215.  
  216.   If you have any suggestions to add to this list, let me know.
  217.   
  218.   
  219. For Programmers
  220.  
  221.     The most recent version of the After Dark programmer’s interface (which
  222.     also gets updated every now and then — the copy you have may
  223.     be outdated!) is available from the major Internet archive sites such
  224.     as sumex.stanford.edu, mac.archive.umich.edu and their mirrors.
  225.  
  226.     The best place to browse if you want to program After Dark modules,
  227.     though, is the Photon Farmer’s FTP site (or their Web pages). You will find
  228.     all kinds of After Dark modules and resources there, and these guys also 
  229.     maintain the After Dark Programmer’s mailing list (archives accessible!)
  230.  
  231.     Finally, you may also want to take a look at ScreenFlip, another screensaver 
  232.     module I wrote, which also comes with documented source code.
  233.  
  234.  
  235.  Final Remark    
  236.  
  237.     Nobody who owns a Macintosh screensaver package should be without
  238.     the most recent version of Lloyd Wood’s Screensaver FAQ (Frequently 
  239.     Asked Questions) List. Copies of this list are also available from all major
  240.     archive sites on or off the Internet. It is a must-have.  
  241.   
  242. Enjoy,
  243.  
  244. __
  245. Leo Breebaart (leo@cp.tn.tudelft.nl)
  246.  
  247. _______________________________________________________________
  248. Appendix: URLs
  249.  
  250.     Here are URLs for some of the Internet resources mentioned in this document. 
  251.   Newer versions of these files may of course have been released by the time
  252.     you read this. Most of the files are available from many other sites as well.
  253.  
  254.     Kronto Software WWW/ftp sites (for info about me and my other programs):
  255.                 http://www.cp.tn.tudelft.nl/leo/kronto.html
  256.                 ftp://kronto.cp.tn.tudelft.nl/pub/macintosh/
  257.     Photon Farmers After Dark Mailing list and FTP Site
  258.                 http://www.phofarm.com/
  259.                 ftp://ftp.phofarm.com/pub/screensavers/mac/afterdark/
  260.     Robert Geisler's Fat Module example code
  261.                 ftp://ftp.phofarm.com/pub/screensavers/mac/afterdark/Fat_Module_Source.sit.hqx
  262.     DarkSide of the Mac 4.2:
  263.                 ftp://ftp.apple.com/dts/mac/hacks/darkside-of-the-mac-4-2.hqx
  264.     Macintosh FAQs WWW/ftp sites:
  265.                 http://www.astro.nwu.edu/lentz/mac/faqs/home-faqs.html
  266.                 http://www.ee.surrey.ac.uk/Personal/L.Wood/screensavers/
  267.                 ftp://rtfm.mit.edu/pub/usenet/news.answers/macintosh/
  268.     Original X-Windows xswarm program:
  269.                 ftp://ftp.x.org/R5contrib/xswarm.2.3.tar.Z 
  270. _______________________________________________________________
  271.  
  272.